Skip to content

Validate declared send scheduling and transaction requirements - #184

Merged
thomhurst merged 2 commits into
mainfrom
issue-7-startup-requirements
Nov 2, 2026
Merged

thomhurst merged 2 commits into
mainfrom
issue-7-startup-requirements

Conversation

@thomhurst

@thomhurst thomhurst commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner

Send routes can now declare RequiredDeliveryDelay and an explicit SendTransactionRequirement on existing SendRouteOptions. Startup validates exact native delay boundaries or an executable durable fallback before consumers start. The existing capability cache is reused; composition resolves scoped outbox capabilities once and retains only immutable values.

Review fix 59dfdd6 caches EF default scheduling capabilities per immutable options version. Sender delivery scopes copy two booleans without constructing SQL-bearing configuration or validating a new options snapshot. Configuration reload updates newly resolved enlistments; existing enlistments keep their defaults, and the selected DbContext's settings still govern scheduling before buffering. The cache retains no scoped services.

Validation on current head 59dfdd6 (Windows with Docker Desktop):

  • Release solution build: 0 warnings, 0 errors.
  • Complete PostgreSQL suite: 174 passed, 0 failed/skipped, including real PostgreSQL behavior and both new regression tests. The options-version test first failed against the previous implementation (two validations for two scopes), then passed after the fix. Tests cover cache reuse, lane/store reload, existing-scope defaults and selected-context overrides.
  • Native AOT win-x64 publish and executable pass. Native execution validates registration and scheduling fallback without a real database; it does not establish an EF compiled-model transaction or native broker transaction round trip.
  • npm ci and npm run build pass. The unchanged 27 dependency audit findings remain tracked in Address documentation dependency audit vulnerabilities #101.
  • Full diff and code-simplifier review pass.
  • Added a [MemoryDiagnoser] scope-resolution benchmark and the performance label. Dry and default runs pass. Allocations fall from 72.35 KB to 3.69 KB per scope, including existing DI/enlistment allocations. These are diagnostic local results; concurrent PostgreSQL tests affected latency variance, so they are not a throughput gate.

Per-message send checks remain constant-time, 0 B added. Default discovery uses an options-monitor cache lookup, a volatile snapshot read and a reference comparison per new enlistment scope; SQL construction, options validation and worker matching are amortized per options version. Active-context checks remain unchanged.

Current evidence: C:/git/Relayer-evidence/pr-184/59dfdd6fb973479d4a9d87229f9f8a64f93d5d13/ (local PR lifecycle retention). Verified 324 copied files against original length and SHA-256, including raw logs, final test reports/binaries, native executable, benchmark reports/binaries and exact source ZIP. Inventory SHA-256: 21C7B9019F3CC4D2866F08A8BAE78FCB6D055F235EC8901D3CB98EB6230BA00D. No generated evidence is committed.

Earlier validation on dbe5098: 964 full-solution tests passed before two final startup tests; final core suite then passed 553 tests and focused capability/sender suite passed 108. This is historical validation, not a full-solution run of the current head. Its separately verified archive remains at C:/git/Relayer-evidence/pr-184/dbe5098d93248e522fbc4de89f21efd0e896593f/ with inventory SHA-256 92CCB6B2027315697A8993C4EA196090D2F8AF092074833B1FF42304A265DDE2.

Closes #7

@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 91efb5b8-83fe-41b9-b460-5b6c174c8084
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

Review of #184: validate declared send scheduling and transaction requirements

I read the diff in full, plus the surrounding Sender and SendRoute code in pr-head/. I did not build or run the tests.

Overall: the design is sound, and I found nothing blocking.

  • Failures are reported at startup and checked again at send time, with actionable messages (D16/D24).
  • Native transactions and outbox durability stay separate. There is no silent fallback, which matches D1.
  • OutboxCapabilities resolves the scoped executor once through a scope and does not retain it.
  • PostgreSqlSchedulingRegistration is only registered by the hosted workers, so "supported" means an actual due-row dispatcher exists, not just that the package is referenced.
  • Sender calls IsActive before SendRoute reads the Supports* properties, so the EF Core _activeConfiguration caching is read in the right order.
  • The per-message cost is two enum compares plus one DeliverAt branch, with 0 B allocated. The PR description does not state this, and AGENTS.md asks for a one-line cost statement. Please add it.

Non-blocking suggestions

  1. EF Core scope setup repeats work. The scoped EntityFrameworkCoreOutbox factory in EntityFrameworkCoreOutboxExtensions.cs now builds a new OutboxConfiguration for every DI scope.
    • The OutboxConfiguration constructor calls PostgreSqlOutboxSchema.CreateScript and builds the insert SQL strings each time.
    • The options and the worker list do not change within a process, so a singleton OutboxConfiguration (or a cached default) would make this a one-time cost.
    • That is closer to the "amortize per connection or consumer" rule in AGENTS.md.
  2. IsActive has a side effect. The getter writes _activeConfiguration, and SupportsScheduling silently depends on it having been called first.
    • This works today, but it is fragile: a caller that reads Supports* first gets the registered default instead of the active context's configuration.
    • Resolving the configuration explicitly, for example through a method that takes the active target, would make the dependency visible.
  3. Duplicate failure messages. SendCapabilityValidator.Validate runs both in SendRouteRegistration.Build and in EndpointCapabilityValidator. A misconfigured route can be reported twice under different location strings. Reporting it from only one place would be less noisy.
  4. Stricter matching for unordered DeliverAt. With an outbox, any unordered DeliverAt now needs a maintenance worker with OrderedLanes == null. A setup that has only an ordered dispatcher rejects unordered scheduled sends. This looks intentional and the error text says so, but a short line in website/docs/reference/postgres-outbox.md would help if it is not already there.

@thomhurst

Copy link
Copy Markdown
Owner Author

Disposition of Claude's current-head review: no blocking findings. The complete validation report has now replaced the initial creation body. Per-message cost: two transaction enum checks and scheduling bool checks, plus a cached EF configuration assignment, 0 B added; no loop, lock, await, copy or capability discovery.

  1. Non-blocking, declined. Outbox options can reload for new scopes; both integrations deliberately use IOptionsSnapshot, and the existing tests cover new-scope reload. A process-wide default configuration would stop respecting those options. Configuration construction remains outside per-message dispatch.
  2. Non-blocking, declined in this change. Sender checks IsActive before the scheduling capabilities, reusing the target scan that already occurs. The scope's default supports startup discovery before a unit is selected. Actual EF enqueue also validates the selected context's configuration before buffering, so changing selection cannot silently persist an unsupported schedule. An additional scan in the capability getter would add work to scheduled sends.
  3. Non-blocking, no defect found. The declaration validator runs in StartingAsync and throws before SendPipeline composition in StartAsync. They do not aggregate two copies into one startup exception. Direct ISender resolution can compose routes before host startup, so it needs the same guard.
  4. Already documented in this head: the PostgreSQL outbox reference explicitly requires maintenance for unordered schedules and ordered dispatch for ordered schedules. The sending guide explains why commit-only dispatch is insufficient.

@thomhurst

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-02T02:43:56.652052Z 59dfdd6 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbe5098d93

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@thomhurst thomhurst added the performance Run the advisory benchmark regression gate on this PR label Nov 2, 2026
@thomhurst

Copy link
Copy Markdown
Owner Author

@codex review

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

Review of PR 184

I read the full diff against AGENTS.md and the design record. I found nothing that should block merge. I did not build or run the tests; the PR's reported pass counts are the only test evidence I have.

What I checked

  • Startup validation. SendCapabilityValidator runs from both SendRouteRegistration.Build and EndpointCapabilityValidator. Native versus Outbox requirements cannot silently substitute for each other. A delay beyond the native MaxDeliveryDelay needs a durable executor that supports scheduling, and ordered routes need ordered scheduling.
  • Scoped services. OutboxCapabilities resolves the scoped IOutboxEnlistment once, inside a short-lived scope, and keeps only an immutable record. No scoped service is retained in the singleton pipeline, which fits the DI and AOT rules.
  • Scheduling support. PostgreSqlSchedulingRegistration is created only by registrations that install a real hosted worker. Matching on schema, prefix and lane count is correct, and the public PostgreSqlOutbox constructor still works.
  • Runtime guards. The new checks in SendRoute.DispatchAsync run before serialization or any durable effect. Their per-message cost is a few enum and null comparisons, 0 B, so no benchmark is needed under the AGENTS.md rule.
  • Tests, docs and AOT. The PR adds unit, PostgreSQL, EF and AOT-smoke coverage, plus updates to the site, docs/design.md and the roadmap.

Non-blocking notes

  1. EntityFrameworkCoreOutbox.IsActive now has a side effect: it caches _activeConfiguration. This is correct as long as the sender reads IsActive before SupportsScheduling, which it does. A short comment on the interface contract, or resolving the configuration inside Add, would make that ordering harder to break.
  2. With TransactionRequirement.None and a RequiredDeliveryDelay beyond the native limit, startup passes because an outbox fallback exists. A direct SendNowAsync with DeliverAt beyond that limit still throws at runtime. The error message is actionable, so this is acceptable, but the docs should state it plainly.

@thomhurst

Copy link
Copy Markdown
Owner Author

Disposition of Claude's review of 59dfdd6: CLEAR; no blocking findings.

  1. Non-blocking; no additional change. Sender already reads IsActive first, and the existing comment explains why the immutable active configuration is cached. OutboxContext.Add also reads the selected context's own configuration and rejects unsupported schedules before buffering; the new selected-context regression test verifies this behavior. No extra target scan is needed.
  2. Already documented in website/docs/guides/sending.md under per-send validation: a direct DeliverAt must fit the native limit, an active transaction is required for fallback, and SendNowAsync always validates the native delay because it bypasses the outbox. RequiredDeliveryDelay is separately documented as a declaration that does not set DeliverAt. No wording change needed.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 59dfdd6fb9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@thomhurst

Copy link
Copy Markdown
Owner Author

Promotion audit for head 59dfdd6: Claude CLEAR and Codex completed without findings both name this head. All review bodies, inline comments, conversation comments and the resolved thread were checked; no later reviewer reply remains undispositioned.

Reverified all 324 files in the current-head archive against the recorded lengths and SHA-256 hashes, plus all 1,387 files in the historical dbe5098 archive. The 30 original files still present also match; worktree cleanup removed the other originals, but their archived copies remain intact. Inventory hashes match the PR description. Durable locations remain C:/git/Relayer-evidence/pr-184/59dfdd6fb973479d4a9d87229f9f8a64f93d5d13/ and C:/git/Relayer-evidence/pr-184/dbe5098d93248e522fbc4de89f21efd0e896593f/ with local PR lifecycle retention. No validation was rerun or newly claimed during this promotion audit.

@thomhurst
thomhurst marked this pull request as ready for review November 2, 2026 02:41
@thomhurst
thomhurst enabled auto-merge (squash) November 2, 2026 02:42
@thomhurst
thomhurst merged commit 177db92 into main Nov 2, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

performance Run the advisory benchmark regression gate on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate configuration against transport capabilities at startup

1 participant